home *** CD-ROM | disk | FTP | other *** search
-
- The BlibII Library Style Guide
- ------------------------------
-
- Although the BlibII linker will handle several different styles for
- BlibII libraries, it may be helpful if the style used is consistent.
- Thus below is a style guide for the structure of BlibII libraries.
-
-
- The Library Introduction
- ------------------------
-
- The library introduction is an important part of the library from the
- users point of view. It details what is contained within the library,
- and any information which covers the library as a whole.
-
- This introduction should form a BlibII block of it's own (ie. should
- have it's own *|start and *|stop, and the block should have the same
- name as the library itself (or a fuller version if the name is
- truncated due to the limit on filename size).
-
- Between the start and stop markers there should be the description
- (using BlibII description commands (*|!), and this description should
- follow the general description rules given below.
-
- There should be no code part to the introduction.
-
-
- Descriptions
- ------------
-
- Descriptions of both the library as a whole, and individual procedures
- and functions should be in a consistent format.
-
- The first line should contain the library name (in the case of a
- library introduction description) or the procedure/function name and
- parameters required (in the case of a procedure/function).
-
- This first line should then be followed by a single blank line
- (containing just the *|! command).
-
- Each line of text should start with the BlibII command *|! and should
- be less than 80 characters long (including the *|!).
-
- Extra blank lines can be included where appropriate, but there should
- be no blank line at the end of the description.
-
- Descriptions should NOT contain any top bit set characters (those with
- ascii values above 127). This is because of a problem with most Basic
- editors (including Acorn's own !Edit) which causes these characters
- to be detokenised upon loading into the editor, but not tokenised back
- again upon saving.
-
- Descriptions can contain any of the formatting commands allowed by the STW
- library's PROCstw_formatline. This means you can have colour changes,
- text left/right justification (justified to 80 chars), centralisation and
- tabulation (to 8 char columns). This means that if you require a '|' in
- your description, you should use '||'.
-
-
- BlibII blocks
- -------------
-
- BlibII defines a block as starting with a '*|!start' command, and a
- '*|!stop' command. Although it is possible for blocks to overlap, it
- is not advised, and can cause problems.
-
- A block should be formatted as follows :
-
- The '*|start' for the block should immediately be followed by the
- description for that block. This description should then be followed by
- the body of the block (the code for the procedure(s)) and then the
- '*|stop' for that block.
-
- The body of the block should contain one blank line at the end of the
- block, this means that extracted procedures will all have one blank
- line separating them in the linked program.
-
- If the block is to be an 'update' block then the format should be :
-
- *|start PROCprocedure
- *|!PROCprocedure ( param1 , param2 )
- *|!
- *|!Description of the procedure and it's parameters
- *|copy
- *|update
- DEFPROCprocedure(A%,B%):REM *** update block ***
- .
- .
- .
- ENDPROC
-
- *|copy
- *|downdate
- *|stop PROCprocedure
-
- Every procedure in the update block should contain a 'REM' comment stating
- that it is in an update block. This clearly warns the user of this fact so
- they can avoid placing new procedures in the update block (which will be
- removed upon linking) or making alterations to the procedures (which will
- be undone upon linking).
-
-
- Procedure/Function names
- ------------------------
-
- In general it is advised to make procedure/function names start with
- the library name (or a shorter version), for example :
-
- PROCwimp_init (Wimp library)
- PROCtemp_init (Template library)
-
- This is not a hard and fast rule, but care should be taken when not
- following this format (try to pick something that is likely to be
- unique, PROCf is NOT acceptable.)
-
-
- Global and Local variables
- --------------------------
-
- Make sure you make all local variables LOCAL (this includes labels in
- assembler code which do not need to be made global, eg. loop pointers,
- etc.). Try to make local variables short, and if possible for integer
- values use A%-Z% then (if 26 not enough) a%-z%, reals a-z and A-Z,
- strings a$-z$ and A$-Z$. This has two advantages, speed and also it
- means that you don't get a mass of different symbols created just for
- local variables.
-
- Global variables should start with an underscore '_' and then be
- followed by the library name (or variant) then another '_' then the
- variable name. Examples :
-
- _wimp_buffer% (Wimp library)
- _mem_error% (Memory library)
-
- Again this is not a hard and fast rule, but it should only be broken
- when there is a good reason for it (and document it).
-
-
-